Document why Pages is off and the Doxygen deploy fails - #16
Open
zeyuyang42 wants to merge 1 commit into
Open
Conversation
The `Deploy Doxygen documentation` job fails on every push to main touching
core/include/** or docs/**, which reads as neglect unless the reason is written
down. It is deliberate: enabling Pages publishes a page under the organization's
website, and that is the org owner's decision to make rather than something to
land as a side effect of a CI change.
docs/design/github-pages-deployment.md records the decision, what actually
fails (only the deploy -- Doxygen generation itself succeeds and the HTML is
built, then discarded), and the two ways to enable it once approved.
It also records why no workflow-side fix exists, so this is not attempted a
third time: `actions/configure-pages` with the default enablement: false only
queries for a site that has never existed, and enablement: true cannot create
one either, because POST /repos/{owner}/{repo}/pages needs admin permission and
`administration` is not a scope `permissions:` can grant to GITHUB_TOKEN. Both
failures are cited to their runs.
The comment above Configure Pages claimed enablement: true "keeps the deploy
self-contained instead of depending on someone having clicked through repository
settings". That was written before the attempt and is false; corrected to say
the step is expected to fail and to point at the design doc. The parameter
itself stays so the file needs no edit if Pages is enabled later.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation only. No behaviour change — the Doxygen deploy still fails, deliberately.
Why
Deploy Doxygen documentationfails on every push tomaintouchingcore/include/**ordocs/**. Without a written reason that reads as a neglected build. It is a decision: enabling Pages publishes a page under the organization's website, which is the org owner's call to make and not something to land as a side effect of a CI change.What's here
docs/design/github-pages-deployment.md— the decision, what actually fails, and how to enable it once approved.Worth stating plainly, because the red X overstates the damage: only the deploy fails.
Generate documentationsucceeds — the HTML is built and then discarded. Runningdoxygen docs/Doxyfilelocally produces the full output underdocs/build/html.The doc also records why no workflow-side fix exists, so this isn't attempted a third time:
GET /repos/ringbuffer-org/Zerr/pages→404.actions/configure-pagesdefaults toenablement: false, which only queries for a site →Get Pages site failed / HttpError: Not Found.enablement: truefails too — creating a site needs admin repo permission, andadministrationis not a scope a workflow'spermissions:block can grant toGITHUB_TOKEN→Create Pages site failed / HttpError: Resource not accessible by integration.Both failures are cited to their runs. The token category is simply wrong for the operation; no configuration change fixes it.
Correction to PR #15
The comment I added above
Configure Pagesclaimedenablement: true"keeps the deploy self-contained instead of depending on someone having clicked through repository settings." That was written before the attempt, and the run disproved it. It now says the step is expected to fail and points at the design doc.The
enablement: trueparameter itself stays. It is inert but harmless — once a site exists the action's initialGetsucceeds andCreateis never reached — so keeping it means no edit is needed here if Pages is switched on later.When you're ready to enable it
Either Settings → Pages → Source: GitHub Actions, or
gh api -X POST repos/ringbuffer-org/Zerr/pages -f build_type=workflowwith an admin token. The workflow passes as written.One gotcha captured in the doc: its
pushtrigger is filtered tocore/include/**anddocs/**, so a settings-only change won't re-trigger it — dispatch manually to confirm.🤖 Generated with Claude Code